\vssub
\subsection{~Running test cases} \label{sec:tests}
\vssub

If \ws\ is installed and compiled successfully, it can be tested by running
 different program elements interactively.  To do this, create a top level 
directory called {\file work} and copy the input files in the {\file model/inp} 
or {\file model/nml} 
directories. A generic switch file is no longer provided, but a switch file can be
chosen from the {\file bin} directory and then test the example input files. 
 It should therefore be possible
to run all model elements by typing
\command{ww3\_grid | more \\
  ww3\_strt | more \\
  ww3\_bound | more \\
  ww3\_prep | more \\
  ww3\_shel | more \\
  ww3\_outf | more \\
  ww3\_outp | more \\
  ww3\_ounf | more \\
  ww3\_ounp | more \\
  ww3\_trck | more \\
  ww3\_grib | more \\
  gx\_outf | more \\
  gx\_outp | more } 
where the {\code more} command is added to allow for on-screen inspection of
the output. This {\code | more} can be replaced by redirection to an output
file, e.g. \command{ww3\_grid > ww3\_grid.out } Note that {\code ww3\_grib}
will only provide GRIB output if a user-supplied packing routine is linked
in. Note furthermore that no simple interactive test case for {\file
ww3\_multi} is provided. GrADS can then be run from the work directory to
generate graphical output for these calculations. All intermediate output
files are placed in the {\file work} directory, and can be removed
conveniently by typing \command{w3\_clean}

Up to version 3.14, \ws\ was provided with a set of simple tests to
established assess the proper behavior of the basic functionality of the
model. In the early development of the next release of the model, Erick Rogers
and Tim Campbell converted these in regression tests that could be run more
easily in an automated version. Up to model version 4.06, these modified tests
were gathered in the {\file nrltest} directory, while keeping the old tests in
the {\file test} directory. In model version 4.07, the {\file nrltest} were
adopted as the new test cases for \ws\ in a new {\file regtests} directory,
while eventually the remaining real-world test cases in {\file test} were
moved to the {\file cases} directory, while discontinuing the {\file test}
directory completely. The following regression tests are available in the
{\file regtests} directory.

\begin{flist}
\fit{ww3\_tp1.1}{1D propagation around the world along the
                 equator (no land).}
\fit{ww3\_tp1.2}{1D propagation, along meridian (no land).}
\fit{ww3\_tp1.3}{1D propagation, shoaling test.}
\fit{ww3\_tp1.4}{1D propagation, spectral refraction ($x$).}
\fit{ww3\_tp1.5}{1D propagation, spectral refraction ($y$)}.
\fit{ww3\_tp1.6}{1D propagation, wave blocking by current.}
\fit{ww3\_tp1.7}{1D propagation, IG wave generation.}
\fit{ww3\_tp1.8}{1D propagation, wave breaking on a beach.}
\fit{ww3\_tp1.9}{1D propagation, Beji and Battjes (1993) barred flume case.}
\fit{ww3\_tp2.1}{2D propagation under angle with grid.}
\fit{ww3\_tp2.2}{2D propagation over half the globe without land (with
                 directional spread). }
\fit{ww3\_tp2.3}{2D propagation, GSE test.}
\fit{ww3\_tp2.4}{2D propagation, East Pacific curvilinear grid test.}
\fit{ww3\_tp2.5}{2D propagation, Arctic Grid, curvilinear grid test.}
\fit{ww3\_tp2.6}{2D propagation, Limon Harbor unstructured grid test.}
\fit{ww3\_tp2.7}{Reflection on a 2D unstructured grid.}
\fit{ww3\_tp2.8}{Tidal constituents on a 2D regular grid.}
\fit{ww3\_tp2.9}{Tests for obstruction grids.}
\fit{ww3\_tp2.10}{Tests for SMC grid.}
\fit{ww3\_tp2.11}{Tests for rotated grid.}
\fit{ww3\_tp2.12}{Test for system tracking.}
\fit{ww3\_tp2.13}{Test for propagation under angle with grid (tripole)}
\fit{ww3\_tp2.14}{Test for toy-model using OASIS coupler.}
\fit{ww3\_tp2.15}{Test for space-time extremes parameters.}
\fit{ww3\_tp2.16}{Two-dimensional propagation on SMC grid with ARC option}
\fit{ww3\_tp2.17}{Unstructured grid with Card Deck vs Domain Decompostion for Explicit vs Implicit schemes}
\fit{ww3\_tp2.16}{Test for two-dimensional SMC propagation with Arctic pole handling}
\fit{ww3\_ts1  }{Source term test, time limited growth.}
\fit{ww3\_ts2  }{Source term test, fetch limited growth.}
\fit{ww3\_ts3  }{Source term test, hurricane with single moving grid.}
\fit{ww3\_ts4  }{Source term test, unresolved obstacles.}
\fit{ww3\_tic1.1}{Wave-ice interaction, 1D test of $S_{ice}$.}
\fit{ww3\_tic1.2}{Wave-ice interaction, 1D test of ``shoaling'' effect.}
\fit{ww3\_tic1.3}{Wave-ice interaction, 1D test of refraction effect.}
\fit{ww3\_tic1.4}{Wave-ice interaction, 1D test with ice floes and ice thickness.}
\fit{ww3\_tic2.1}{Wave-ice interaction, 2D test of $S_{ice}$.}
\fit{ww3\_tic2.2}{Wave-ice interaction, 2D test with non-uniform ice.}
\fit{ww3\_tic2.3}{Wave-ice interaction, 2D test with uniform ice with increasing thickness.}
\fit{ww3\_tbt1.1}{Wave-mud interaction, 1D test of $S_{mud}$.}
\fit{ww3\_tbt2.1}{Wave-mud interaction, 2D test of $S_{mud}$.}
\fit{ww3\_tpt1.1}{Tests for alternative spectral partitioning methods.}
\fit{ww3\_ta1   }{ww3\_uprstrt, update the restart file of homogeneous conditions (1 point model)}
\fit{mww3\_test\_01}{Test for expanded grid mask with wetting and drying, etc.}
\fit{mww3\_test\_02}{Two-way nesting test with single inner grid.}
\fit{mww3\_test\_03}{Overlapping grids and two-way nesting tests (6-grid
                     version with beach in high-resolution grids.)}
\fit{mww3\_test\_04}{Current or sea-mount test for two-way nesting with
                     stationary swell conditions.}
\fit{mww3\_test\_05}{Three nested hurricane grids with moving grids test.}
\fit{mww3\_test\_06}{Tests for irregular grid(s) w/ {\file ww3\_multi}.}
\fit{mww3\_test\_07}{Tests for unstructured grid(s) w/ {\file ww3\_multi}.}
\fit{mww3\_test\_08}{Tests with wind and ice input.}
\end{flist}

\noindent
These regression tests are now run using the {\file run\_test} script in the
{\file regtests/bin} directory (primary author: Tim Campbell). How to run this
script, including options, is shown by running \command{run\_test -h} The
output of running this command is shown here in Fig.~\ref{fig:runtest}.  The
test cases are stored in directories under the {\file regtests} directory,
e.g.  {\file regtests/ww3\_tp1.1}. For example, the contents of {\file
/ww3\_tp1.1} might be

\begin{flist}
\fit{info }{A file containing information about the test case.} 
\fit{input}{A permanent directory containing input files for the test case.}
\fit{work\_PR3}{A scratch directory for model output (in this example,
    filename is such because the user had specified ``{\file run\_test -w work\_PR3
      ...''}).}
\end{flist}

\noindent
Also provided now is a matrix if regression tests, used by the code developers
to assure that new model versions do not break older model versions. The core
of this matrix is the file {\file regtests/bin/matrix.base}. An example of how
to run this is given in {\file regtests/bin/matrix\_zeus\_HLT}, which is
Hendrik's driver for the matrix at the NCEP Zeus R\&D
computer\footnote{~Please build your own driver for your own setup using this
as a blueprint, rather than editing this file.}. To run this, make a link to
it in the {\file regtests} directory and execute after setting the desired
option flags in the script. This will make a file {\file matrix} in {\file
retests}, which can then be run interactively or in batch mode as desired. The
file can also be manually edited further if so desired. The {\file bin}
directory under {\file regtests} contains the following tools.

\begin{flist}
\fit{cleanup          }{Cleanup work directories.}
\fit{comp\_switch     }{Compare switches inside and across test cases.
                        {\file comp\_switch -h}  provides documentation.}
\fit{matrix.base      }{Core script to generate matrix of test cases.}
\fit{matrix.comp      }{Script to compare output of matrix of test cases
                        between separately checked out model versions.}
\fit{matrix\_zeus\_HLT}{Example of driver for {\file matrix.base}.}
\fit{run\_test        }{Basic test script as described above.}
\end{flist}

\noindent 
Note that efficient running of the matrix of regression tests requires a
minimization of the need to recompile code between regression tests. This is
achieved by the ordering of the regression tests in {\file matrix.base}. A way
to assure that identical switch files are identified as such is to
systematically sort them. This can be done with the script {\file
sort\_switch} in the main {\file bin} directory. This script will add default
values of missing switches and can also be used to remove or add switches from
the file. Run \command{comp\_switch -h} for documentation of the script.

\vspace{\baselineskip} \noindent 
Finally, the {\file cases} directory hold the real-world test cases as
described below.

\begin{flist}
\fit{mww3\_case\_01}{Atlantic case with five grids focusing on Trondheim.}
\fit{mww3\_case\_02}{Pacific case with three grids focusing on Alaska.}
\fit{mww3\_case\_03}{Original multi-grid case used as global model at NCEP.}
\end{flist}

\noindent 
Each of these cases is a single script executing the entire model run. Before
executing the script, compile the model with the switches indicated in the
documentation at the head of the script. Additional data used by these scripts
is contained in the directories

\begin{flist}
\fit{mww3\_data\_00}{Wind fields and ice data used by all example cases.}
\fit{mww3\_data\_{\it nn}}{Specific data needed for script {\file
                           mww3\_case\_{\it nn}}.}
\end{flist}

\noindent 
These examples can be used as blueprints for setting up other real model
applications.

\input{impl/fig_runtest}
